home *** CD-ROM | disk | FTP | other *** search
/ The X-Philes (2nd Revision) / The X-Philes Number 1 (1995).iso / xphiles / hp48_2 / areuh.tar / areuh / doc / readme.dos < prev   
Text File  |  1990-10-10  |  16KB  |  502 lines
  1.               HP-71 DEVELOPMENT SYSTEM
  2.  
  3.  
  4.  
  5.  
  6.  
  7. NOT FOR COMMERCIAL DISTRIBUTION - NOT FOR COMMERCIAL DISTRIBUTION - NOT FOR
  8. MMERCIAL DISTRIBUTION - NOT FOR COMMERCIAL DISTRIBUTION - NOT FOR COMMERCIA
  9. ISTRIBUTION - NOT FOR COMMERCIAL DISTRIBUTION - NOT FOR COMMERCIAL DISTRIBU
  10.  
  11.  
  12.  
  13.  
  14. Notice :  this is a public  domain  software.  You are    encouraged  to make
  15. copies of it.  Feel free to distribute it.  The only restriction is that it
  16. cannot be distributed on a commercial basis.
  17.  
  18.  
  19.  
  20.  
  21. INTRODUCTION
  22. ------------
  23.  
  24.  
  25. This disk contains the AREUH development system.  It is intended to produce
  26. LEX or BIN files for the HP-71B, using a PC or    compatible  computer.  This
  27. system    includes an  assembler, a linker, a message  table  generator,    and
  28. miscellaneous useful tools.
  29.  
  30. It is a sophisticated  set of programs.  They have been optimized for speed
  31. without compromising capabilities.  The assembler is able to process source
  32. files  either  compatible  with  Forth /  Assembler  Rom or HP    development
  33. system.  It should be able to  understand  all    source    file  formats.    The
  34. linker is a  convenient  tool to develop  large  projects  as well as small
  35. ones.  The table message  generator (like other tools) is very easy to use,
  36. and greatly simplify the creation of such tables.
  37.  
  38. It was written by Pierre David and Janick  Taillandier, from PPC-Paris.  We
  39. are happy to thank Stephane  Barizien for its efficient help for all MS-DOS
  40. problems.
  41.  
  42. As described above, you are welcome to copy and distribute it free. We hope
  43. it will help HP-71 software development. It is our common interest.
  44.  
  45. It was used by the authors to develop :
  46.  
  47. - JPCROM (19+ KB Lex file, 461 KB source files, assembled in 2.20 minutes)
  48.   JPCROM is the PPC-Paris LEX file, including 100 various keywords.
  49.  
  50. - GRAPHIC (9 KB Lex file, 290 KB source files, assembled in 1.15 minutes)
  51.   GRAPHIC is a commercial product, providing graphic  capabilities  similar
  52.   to HP-85,  HP-41,  HP-200  graphic  languages on a ThinkJet  (MOVE, DRAW,
  53.   LABEL...).
  54.  
  55.  
  56. I - HISTORY
  57. -----------
  58.  
  59.  
  60. The AREUH  development    system (AREUH stands for  Assembleur  Relogeable En
  61. Utilisation  Heuristique) was developed from April to August 1986 on a UNIX
  62. machine :  the HP Integral Personal  Computer.    Unfortunately,    many people
  63. are now using PC or compatible.  So, in July 1987, we have decided to adapt
  64. AREUH to these so called computers.
  65.  
  66. The process was rather hard for us :  we had to find a PC, a C compiler, an
  67. HPIL card, etc.  We also had a lot of  difficulties  with the  surprising C
  68. compiler  implementation,  as well as with the numerous but powerless  text
  69. editors...
  70.  
  71. We have no personal interest in this MS-DOS version.  It was a tough job to
  72. get it work, and we get no profit from it.
  73.  
  74. This was done to allow all HP-71  developers  to benefit  from our tool and
  75. stop using  archaic ones, and we hope to see more HP-71  software.  We wish
  76. this could help.
  77.  
  78. We hope the time we have spent on this    project will not be a wasted  time.
  79. We would appreciate receiving feed-back from you.  It would also be nice to
  80. mention that your software has been developed with this assembler.
  81.  
  82.  
  83. II - WHY A LINKER ?
  84. -------------------
  85.  
  86.  
  87. If you take a look at the IDS Vol.  III, or HPIL IDS, you may  notice  that
  88. HP used a linker.  Other  large  projects,  such as JPCROM or GRAPHIC  have
  89. been using a linker.
  90.  
  91. Using a linker    allows    splitting a large  problem  into small,  manageable
  92. units :  you have only small  files to edit and  assemble.  You divide your
  93. problem  into  functional  units,  with clear  interfaces.  You work on one
  94. module at a time, you don't have to take care of the others.
  95.  
  96. Incidentally,  you spare time because you have only one module to assemble,
  97. and you have small convenient  facilities,  such as local labels known only
  98. inside the module, and global ones known everywhere.
  99.  
  100.  
  101. III - PRINCIPLE
  102. ---------------
  103.  
  104.  
  105. A : THE TWO MODES
  106. -----------------
  107.  
  108. The assembler has two operating modes :
  109.  
  110. - compatibility mode
  111. - modular mode
  112.  
  113. The first one is  intended to assemble    all source  files  written  for the
  114. Assembler  Rom.  All  macro-operations    such  as  LEX,    BIN,  CHAIN...    are
  115. supported.  No linkage step is needed.
  116.  
  117. The second one is similar to the description  given in IDS Vol.  I, chapter
  118. 16.  In  fact, it has more  features  than  this  one.    This  mode  needs a
  119. linkage  step, and  supports  local and global    labels.  A global  label is
  120. preceded by an "=" character.
  121.  
  122. To use the compatibility  mode, the first line of the file must be a LEX or
  123. BIN macro-operation.  Any other first line activates modular mode.
  124.  
  125. If you wish to use system entry points in  compatibility  mode, you can use
  126. the RDSYMB  macro-operation.  It will read the    specified  file to load all
  127. supported entry points.  You don't need any more to write long lists of EQU
  128. to use system entry points.
  129.  
  130. In  modular  mode,   everything  is  automatic.  The  system  entry  points
  131. addresses are loaded at link time.
  132.  
  133. In both  modes, you cannot use FORTH, WORD and WORDI  macro-operations.  In
  134. modular  mode, you cannot use LEX, ID, MSG, POLL, ENTRY, CHAR,    TOKEN, KEY,
  135. ENDTXT, BIN and CHAIN.
  136.  
  137.  
  138. B : LISTINGS
  139. ------------
  140.  
  141. You can  output  assembler  or    linker    listings,  with  optional  complete
  142. cross-reference  section.  For an  example,  see  FINPUT  listing  in JPC43
  143. (April 1987).
  144.  
  145.  
  146. C : ADDED FEATURES
  147. ------------------
  148.  
  149. Compared with the Assembler  Rom, or HP's one, the following  features have
  150. been added :
  151.  
  152. - label  names    may have up to 12  significant    characters  (13 if they are
  153. preceded by an "=" symbol).
  154.  
  155. - all  opcodes and  modifiers  are not case  sensitive.  You can mix freely
  156. lower and upper case characters.  Label names are always case sensitive.
  157.  
  158. - conditional assembly is allowed, with macro-operation IF. The syntax is :
  159.        IF     <expression>
  160.     <assembled if expression # 0>
  161.        ELSE
  162.     <assembled if expression = 0>
  163.        ENDIF
  164.  
  165. The ELSE part is optional.
  166.  
  167. - the  macro-operation    RDSYMB (ReaD SYMBol) was implemented to load a file
  168. containing entry points.  The syntax is :
  169.        RDSYMB <filename>
  170. In this MS-DOS version,  <filename> can be an absolute file reference (such
  171. as  a:\lib\hp71.ep),  or a  relative  one.  In the last  case,    the file is
  172. looked for in specific locations.
  173.  
  174. - D0=HEX and D1=HEX,  undocumented  and bugged opcodes in the Assembler Rom
  175. are present and unbugged !
  176.  
  177. - numerical values are processed on 6 hexadecimal  digits  (nibbles), as in
  178. HP's assembler.  This allows providing LC(6) and CON(6) instructions.
  179.  
  180. -  litteral  constants    may  be  delimited  either  by '  (quote)  or  by \
  181. (backslash) symbols.
  182.  
  183. - there is no limit on parenthesis level.
  184.  
  185. - a new constant type is supported :  binary constants.  They are used with
  186. a % symbol :  for example :  %01110001 = #71 = 113.
  187.  
  188. - new operators have been added. They are
  189.    ~   -> *256+
  190.    ^   -> power
  191.    `   -> one's complement
  192. All operators are listed below, in descending order or precedence.
  193.    ~   (*256+)                 ^     (power)
  194.    -   (unary minus)             `     (one's complement)
  195.    &   (logical and)             !     (logical or)
  196.    *   (multiplication)          /     (integer division)
  197.    +   (addition)             -     (binary subtraction)
  198.  
  199. - FiLeNd label is automatically  added at the end of each assembled file or
  200. module.  In modular  mode, a global label  =FiLeNd is  automatically  added
  201. after the last module during link step.
  202.  
  203.  
  204. IV - USING THE PROGRAMS
  205. -----------------------
  206.  
  207.  
  208. A : File naming conventions :
  209. -----------------------------
  210.  
  211. - source files have the ".as" (Areuh Source) extension,
  212. - object file resulting from assembly in modular mode have the ".ao" (Areuh
  213.   Object) extension,
  214. - list files have the ".al" (Areuh List) extension,
  215. - message description files have the ".am" (Areuh Message) extension,
  216. - entry points files have the ".ep" (Entry Point) extension,
  217. - complete lex files (result of aas in compatibility mode or ald) are named
  218.   "lex".
  219.  
  220. These  are  suggested  names.  You can    override  them    using  full  names.
  221. However, using them is easier.
  222.  
  223.  
  224. B : Assembler (aas) and Linker (ald)
  225. ------------------------------------
  226.  
  227. Both programs share the same options.
  228.  
  229. -o <file>
  230. specifies  the name of output file.  If the specified  name is a directory,
  231. the output file is written in this directory, using default name.
  232.  
  233. -a <file>
  234. produces  a listing  in the  specified    file.  If the  specified  name is a
  235. directory,  the listing file is written in this  directory,  using  default
  236. name.
  237.  
  238. -A
  239. produces a listing on standard output.
  240.  
  241. -l <page length>
  242. specifies  the physical page length in number of lines    (default is 72, for
  243. 12" paper).  Text length is (page length - 6).
  244.  
  245. -x
  246. asks  for a  cross-reference  table.  Should  be used  only  when  -a or -A
  247. options are specified.
  248.  
  249. -p
  250. enables  interactive options input.  If no option or file name is specified
  251. after aas or ald, you automatically enter interactive prompt mode.
  252.  
  253. After aas, you have to supply the source  file names (wild card  characters
  254. allowed).  File names order is irrelevant.
  255.  
  256. After  ald, you have to supply    the  intermediate  file  names    (wild  card
  257. characters allowed).  File names order is very important, it corresponds to
  258. the link order.
  259.  
  260.  
  261. The  linker is    limited  to 80 files.  As far as MS-DOS  command  lines are
  262. limited to a small  numbers of    characters,  you may have  difficulties  to
  263. specify  a full  ald  command.    In  this  case,  you  can  use    interactive
  264. prompting :
  265.   ald  <answer
  266. where "answer" is a text file containing the answers to all questions.
  267.  
  268.  
  269. C : Message table generator (amg)
  270. ---------------------------------
  271.  
  272. Amg reads on  standard    input a message  table    description,  and writes on
  273. standard output an HP-71 message table, ready to be assembled.
  274.  
  275. The message table  description    contains  several lines with the  following
  276. structure :
  277.  
  278. <message label>:<message text>
  279.  
  280. For example :
  281. =eDIRFL:Directory Full
  282.  
  283. If you    want to use  building  blocks,    the  building  block  text  must be
  284. enclosed within square brackets, for example :
  285. =eUNEXP:Unexpected [Message ]
  286. [Message ] (with a  white  space)  is a local  building  block.  It will be
  287. created in the message table.
  288.  
  289. Amg recognizes automatically mainframe building blocks. For example :
  290. =eBADMD:[Invalid ]Mode
  291. [Invalid ] (with a white space) is a mainframe building block.    The message
  292. table will reference it without creating it.
  293.  
  294. Messages  are  numbered  from 0.  If an  argument  is  given,  it must be a
  295. number, and messages will be numbered from it.
  296.  
  297. Amg checks  that there is a message  whose total  length is multiple  of 16
  298. nibbles, as requested by the HP-71  Operating  System.    Otherwise, an error
  299. is written in the generated file.
  300.  
  301.  
  302. D : Downloading to HP-71 :
  303. --------------------------
  304.  
  305. Two  utilities are provided to download the  assembled    files to the HP-71.
  306. You can use either the RS232 interface or the HP82973 HPIL interface.
  307.  
  308.  
  309. RS232 : (program a2rs)
  310. ----------------------
  311.  
  312. The syntax is : a2rs [ <file> ]
  313. If no file name is specified, the default is "lex".
  314.  
  315. For the connection, we have used the following cable :
  316.  
  317.        PC           HP82164A RS232/HPIL
  318.  
  319.     2 ----\ /----  2
  320.            x
  321.     3 ----/ \----  3
  322.  
  323.     4 ----\ /----  4
  324.            x
  325.     5 ----/ \----  5
  326.  
  327.     6 ----\ /----  6
  328.            x
  329.        20 ----/ \---- 20
  330.  
  331.     7 -----------  7
  332.  
  333.  
  334. The HP82164A must be configured from the HP-71 by :
  335.   REMOTE @ OUTPUT :RS232;"LI5;C0" @ LOCAL
  336. before running a2rs, you have to enter on your HP-71 :
  337.   COPY :RS232
  338.  
  339.  
  340. HPIL : (program a2lex)
  341. ----------------------
  342.  
  343. Prior to transfer  your  assembled  file, you must use a2lex to convert the
  344. file to the format needed by HPILLINK.
  345.  
  346. The syntax is : a2lex [ <file> ]
  347. If no file name is specified,  the default is "lex".  The ".lex"  extension
  348. is automatically appended to the converted file.
  349.  
  350. Then, you can download using HPILLINK.
  351.  
  352.  
  353. CUSTOMIZING YOUR DOWNLOADING PROGRAM : (program a2?)
  354. ----------------------------------------------------
  355.  
  356. The syntax will be : a2? [ <file> ]
  357. If no file name is specified, the default is "lex".
  358.  
  359. In order to allow you to use any device you may wish to download  your LEX,
  360. we give you the source code for a2lex (file a2lex.c) as an example.
  361.  
  362. You have to write only three functions in C :
  363.   init () :
  364.     initializes your interface
  365.   output (char c) :
  366.     outputs the character c to your interface
  367.   term () :
  368.     terminates the process.
  369.  
  370. These functions can be empty.  They are only responsible for the interface,
  371. and not for the conversion process.
  372.  
  373.  
  374. V - EXAMPLES
  375. ------------
  376.  
  377.  
  378. To assemble "compat.as" (compatibility mode), you must type :
  379.   aas compat
  380. The output will be in "lex" file.
  381.  
  382.  
  383. To assemble  "compat.as" with listing and cross-reference  section, sent to
  384. file "list", type :
  385.   aas -xalist -l66 compat     or
  386.   aas -x -a list -l 66 compat.as
  387.  
  388.  
  389. To assemble the same file with interactive options input, simply type :
  390.   aas
  391.     then enter "compat"
  392.     then press [RETURN]      (output is default, "lex")
  393.     then enter "list"            (for listing file)
  394.     then enter "yes"             (for cross reference)
  395.     then enter "66"              (for page length)
  396.  
  397.  
  398. To assemble files "x1.as", "x2.as", "x3.as" (modular mode), you must type :
  399.   aas x*.as             or
  400.   aas x1 x2 x3
  401.  
  402. To link these files, with a listing and cross-reference in file "list", and
  403. a lex file in "totolex", you must type :
  404.   ald -xalist -ototolex x1 x2 x3
  405. Warning : the order of object modules if important.
  406.  
  407.  
  408. To create a message table from "jpc.am", you must type :
  409.   amg <jpc.am >mes.as
  410.  
  411. If you wish to number these messages starting from 27, you must type :
  412.   amg 27 <jpc.am >mes.as
  413.  
  414.  
  415. VI - ENTRY POINTS FILES
  416. -----------------------
  417.  
  418.  
  419. AREUH is provided with two files :
  420.  
  421.   hp71.ep :       mainframe supported entry points and symbols
  422.   hpil.ep :       hpil supported entry points
  423.  
  424. These files are looked for in the following directories :
  425.   current directory
  426.   c:\hp71\
  427.   c:\lib\hp71\
  428.   c:\lib\
  429.   c:\areuh\lib\
  430. or at the location specifed by RDSYMB.
  431.  
  432. You can add entry  points to these files, or use other files.  Only hp71.ep
  433. is  automatically  loaded at link time.  If you want to use hpil.ep or your
  434. own file, you must load them explicitly at assembly time with RDSYMB.
  435.  
  436. The  supplied  files are  sorted in reverse  order.  This is only for speed
  437. considerations.  Each label has its name, followed by its hexadecimal value
  438. on the next line.
  439.  
  440. If you find any error in these files, please inform us.
  441.  
  442.  
  443. VII - IN CASE OF PROBLEMS
  444. -------------------------
  445.  
  446. If you have a  problem,  before  reporting  it to us,  please  check if the
  447. problem is not in your source code or computer system.
  448.  
  449. We will try to answer your  questions or solve your  problems (NOT hardware
  450. or  connection    problems).  Send us on a 3.5" LIF (or MS-DOS)  format  your
  451. source code, with a complete  description and localization of your problem.
  452. This is not a programming aid service...
  453.  
  454. Write to :
  455.   Pierre David         or        Janick Taillandier
  456.   33 Bd St Martin            335 rue Lecourbe
  457.   75003 Paris                75015 Paris
  458.   FRANCE                FRANCE
  459.  
  460.  
  461. APPENDIX 1 : DISTRIBUTION DISK
  462. ------------------------------
  463.  
  464.  
  465. This disks contains the following files :
  466.  
  467. aas.exe     Areuh ASsembler
  468. ald.exe     Areuh LoaDer (Loader = Linker under UNIX)
  469. amg.exe     Areuh Message table Generator
  470. a2lex.exe    Areuh To HPILLINK LEX format
  471. a2rs.exe    Areuh To RS232
  472. adp.exe     Areuh DumP (utility to dump intermediate files)
  473.  
  474. readme        This file
  475.  
  476. xmp\compat.as    Example for compatibility mode
  477. xmp\x1.as    Example for modular mode (file header)
  478. xmp\x2.as    Example for modular mode (execution routine)
  479. xmp\x3.as    Example for modular mode (decomparse routines)
  480. xmp\jpc.am    Example of message table description (from JPCROM)
  481.  
  482. src\copy.h    body of a2lex program
  483. src\a2lex.c    dedicated I/O routines
  484.  
  485. lib\hp71.ep    HP-71 supported entry points and symbols
  486. lib\hpil.ep    HP-IL supported entry points
  487.  
  488.  
  489. APPENDIX 2 : MS-DOS NOTE
  490. ------------------------
  491.  
  492. These programs have been successfully  tested on an HP 150, MS-DOS 2.11 and
  493. on an AT compatible MS-DOS 3.20.
  494.  
  495. We have used Microsoft C 4.0 to compile all programs.
  496.  
  497.  
  498.  
  499. Enjoy !
  500.  
  501. Pierre David & Janick Taillandier
  502.